Multi-channel devices: pick which channels TeamTalk uses per device - #39

Reviewed against current main (06aaf77). I pulled the branch into a worktree, merged main into it, and built the result: no conflicts despite the 23-commit gap, clean Debug build with no new warnings in any of the touched files, and 78 tests green (65 from main + your 13). OutputChannelPickerVisibilityTests actually ran on my machine rather than skipping.

The design holds up well, and a few things are worth saying out loud because they were done right:

• Bounds are checked twice on the RT path — planeIndices(deviceChannels:) clamps in Swift, ttac_render_planes re-validates against devCh in C before dereferencing. A stale selection falls back to 1/2 instead of writing into foreign memory. Same on the capture side: resolveChannelSelection clamps against the channel count the AUHAL actually reports, and handleInput reads that same captureChannels, so no out-of-buffer read is reachable.
• Packing the pair into planeMapCell is the right call — it's exactly what stops a callback from reading a new left with an old right, and it stays consistent with the existing gain/mute cells.
• The ordering works out: setChannelSelection is engineQueue.async while start/switchDevice are engineQueue.sync, so the async lands first; and publishChannelMappingLocked() sits after deviceChannels = devChannels and before the release fence.
• The willSet note deserves the long comment it got.

Below is what I'd like changed before this goes in. Push back on any of it if you disagree — several are judgement calls and you know this hardware better than I do.

Tests

1. The regression test only fires on the right hardware. OutputChannelPickerVisibilityTests does XCTSkip without a >2-channel output device. It passed here, but on a machine without an interface it goes silently green — so the willSet bug it protects could come back with nothing turning red. The core of that bug is pure logic. If refreshOutputChannelState grew a small pure helper along the lines of resolveSelection(preferences:uid:channelCount:), that part would be testable with no CoreAudio at all, and the hardware test could stay as a complement.

2. Same test breaks the suite's rule. CLAUDE.md says the tests deliberately don't touch AppKit, CoreAudio, or the TeamTalk SDK runtime; this one builds a real TeamTalkConnectionController and enumerates CoreAudio. The split in (1) fixes both at once.

3. The UserDefaults cleanup isn't guaranteed. removePersistentDomain only runs at the end, so a failing assert leaves the plist behind. main just fixed that same pattern elsewhere in 2e82d45 — a defer or tearDown would match.

Code

4. "Glitch-free" is a little optimistic (OutputAudioRenderEngine.setChannelSelection). The remap is instant: the old plane drops to zero and the new one starts at full amplitude mid-waveform. Gain smoothing doesn't cover that discontinuity, so a click is possible on both outputs. It's a rare, deliberate action so I'm fine shipping it as is — but either the comment should say "no rebind" rather than "glitch-free", or it needs a short ramp. Your ears, your call.

5. The two input pickers disagree on the threshold. offersInputChannelSelection gates at >= 2, and your reasoning for that is right. But updateChannelOptions in the stream sheet gates at > 2, so on a plain stereo interface "Input 1 mono" is available for the mic and not for streaming. The same argument applies to both.

6. applyOutputChannelSelectionLocked sits before the early return. It enumerates CoreAudio (availableOutputDevices() in the system-default case) on every applyAudioPreferences, including the calls the guard was about to drop. Only four call sites and nothing real-time, so it's not urgent — it just gives back what the early return was buying.

7. Two sources of truth in one function. applyOutputChannelSelectionLocked(preferences:) reads usesNoOutput and outputChannelSelections from the parameter, but resolves the device through resolveOutputEngineDeviceLocked(), which reads preferencesStore.preferences. I checked all four callers — every one passes preferencesStore.preferences, so it's harmless today. It's a trap for whoever passes a snapshot next.

Docs

8. The user guide landed on main after you opened this. There's a Help Book now (Help/Source/{en,fr}), and neither "Output channels" in Preferences ▸ Audio nor the "Channels" picker in the stream sheet appears anywhere in it. After the rebase: 65-audio-setup.md and 75-streaming.md, both languages, then regenerate the bundle with ./scripts/build-help-book.sh.

Wording (VoiceOver)

9. "Auto" on its own doesn't say it means outputs 1/2 — something like "Auto (outputs 1/2)" would. And on a 24-out interface the menu is 49 items with all 24 monos ahead of the 12 pairs, when the pair is the common case; putting pairs first would cut the keyboard trip. Minor: "Outputs 5/6 stereo" reads as "5 slash 6" in speech — "Outputs 5 and 6" may land better. You're the better judge of all three.

Happy to merge once (1)–(3) and (8) are handled — the rest is polish that can follow. Two things I couldn't verify and that want your ears: the possible click in (4), and the stream-sheet picker, since you noted your iD44 pass predates the port onto the new sheet.